<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>NRE manual page - Tcl Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> NRE</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="NRE.htm#M2" NAME="L508">NAME</A>
<DL><DD>Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback &mdash; Non-Recursive (stackless) evaluation of Tcl scripts.</DD></DL>
<DD><A HREF="NRE.htm#M3" NAME="L509">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tcl.h&gt;</B>
<DD>Tcl_Command
<DD><B>Tcl_NRCreateCommand</B>(<I>interp, cmdName, proc, nreProc, clientData,
<DD>deleteProc</I>)
<DD>int
<DD><B>Tcl_NRCallObjProc</B>(<I>interp, nreProc, clientData, objc, objv</I>)
<DD>int
<DD><B>Tcl_NREvalObj</B>(<I>interp, objPtr, flags</I>)
<DD>int
<DD><B>Tcl_NREvalObjv</B>(<I>interp, objc, objv, flags</I>)
<DD>int
<DD><B>Tcl_NRCmdSwap</B>(<I>interp, cmd, objc, objv, flags</I>)
<DD>int
<DD><B>Tcl_NRExprObj</B>(<I>interp, objPtr, resultPtr</I>)
<DD>void
<DD><B>Tcl_NRAddCallback</B>(<I>interp, postProcPtr, data0, data1, data2, data3</I>)
</DL>
<DD><A HREF="NRE.htm#M4" NAME="L510">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DL class="arguments">
</DL>
<DD><A HREF="NRE.htm#M5" NAME="L511">DESCRIPTION</A>
<DD><A HREF="NRE.htm#M6" NAME="L512">EXAMPLE</A>
<DD><A HREF="NRE.htm#M7" NAME="L513">SEE ALSO</A>
<DD><A HREF="NRE.htm#M8" NAME="L514">KEYWORDS</A>
<DD><A HREF="NRE.htm#M9" NAME="L515">COPYRIGHT</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback &mdash; Non-Recursive (stackless) evaluation of Tcl scripts.
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
<A HREF="../TclLib/CrtObjCmd.htm">Tcl_Command</A><BR>
<B>Tcl_NRCreateCommand</B>(<I>interp, cmdName, proc, nreProc, clientData,<BR>
<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>deleteProc</I>)<BR>
int<BR>
<B>Tcl_NRCallObjProc</B>(<I>interp, nreProc, clientData, objc, objv</I>)<BR>
int<BR>
<B>Tcl_NREvalObj</B>(<I>interp, objPtr, flags</I>)<BR>
int<BR>
<B>Tcl_NREvalObjv</B>(<I>interp, objc, objv, flags</I>)<BR>
int<BR>
<B>Tcl_NRCmdSwap</B>(<I>interp, cmd, objc, objv, flags</I>)<BR>
int<BR>
<B>Tcl_NRExprObj</B>(<I>interp, objPtr, resultPtr</I>)<BR>
void<BR>
<B>Tcl_NRAddCallback</B>(<I>interp, postProcPtr, data0, data1, data2, data3</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in)<DD>
The relevant Interpreter.
<P><DT>char <B>*cmdName</B> (in)<DD>
Name of the command to create.
<P><DT><A HREF="../TclLib/CrtObjCmd.htm">Tcl_ObjCmdProc</A> <B>*proc</B> (in)<DD>
Called in order to evaluate a command.  Is often just a small wrapper that uses
<B>Tcl_NRCallObjProc</B> to call <I>nreProc</I> using a new trampoline.  Behaves
in the same way as the <I>proc</I> argument to <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CreateObjCommand</A></B>(3)
(<I>q.v.</I>).
<P><DT><A HREF="../TclLib/CrtObjCmd.htm">Tcl_ObjCmdProc</A> <B>*nreProc</B> (in)<DD>
Called instead of <I>proc</I> when a trampoline is already in use.
<P><DT>ClientData <B>clientData</B> (in)<DD>
Arbitrary one-word value passed to <I>proc</I>, <I>nreProc</I>, <I>deleteProc</I>
and <I>objProc</I>.
<P><DT><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CmdDeleteProc</A> <B>*deleteProc</B> (in/out)<DD>
Called before <I>cmdName</I> is deleted from the interpreter, allowing for
command-specific cleanup. May be NULL.
<P><DT>int <B>objc</B> (in)<DD>
Number of items in <I>objv</I>.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>**objv</B> (in)<DD>
Words in the command.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>*objPtr</B> (in)<DD>
A script or expression to evaluate.
<P><DT>int <B>flags</B> (in)<DD>
As described for <I><A HREF="../TclLib/Eval.htm">Tcl_EvalObjv</A></I>.
<P></DL>
<P>
<P>
<DL class="arguments">
<DT><A HREF="../TclLib/CrtObjCmd.htm">Tcl_Command</A> <B>cmd</B> (in)<DD>
Token to use instead of one derived from the first word of <I>objv</I> in order
to evaluate a command.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>*resultPtr</B> (out)<DD>
Pointer to an unshared <A HREF="../TclLib/Object.htm">Tcl_Obj</A> where the result of the evaluation is stored if
the return code is TCL_OK.
<P><DT>Tcl_NRPostProc <B>*postProcPtr</B> (in)<DD>
A function to push.
<P><DT>ClientData <B>data0</B> (in)<DD>
<P><DT>ClientData <B>data1</B> (in)<DD>
<P><DT>ClientData <B>data2</B> (in)<DD>
<P><DT>ClientData <B>data3</B> (in)<DD>
<I>data0</I> through <I>data3</I> are four one-word values that will be passed
to the function designated by <I>postProcPtr</I> when it is invoked.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These functions provide an interface to the function stack that an interpreter
iterates through to evaluate commands.  The routine behind a command is
implemented by an initial function and any additional functions that the
routine pushes onto the stack as it progresses.  The interpreter itself pushes
functions onto the stack to react to the end of a routine and to exercise other
forms of control such as switching between in-progress stacks and the
evaluation of other scripts at additional levels without adding frames to the C
stack.  To execute a routine, the initial function for the routine is called
and then a small bit of code called a <I>trampoline</I> iteratively takes
functions off the stack and calls them, using the value of the last call as the
value of the routine.
<P>
<B>Tcl_NRCallObjProc</B> calls <I>nreProc</I> using a new trampoline.
<P>
<B>Tcl_NRCreateCommand</B>, an alternative to <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CreateObjCommand</A></B>,
resolves <I>cmdName</I>, which may contain namespace qualifiers, relative to the
current namespace, creates a command by that name, and returns a token for the
command which may be used in subsequent calls to <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_GetCommandName</A></B>.
Except for a few cases noted below any existing command by the same name is
first deleted.  If <I>interp</I> is in the process of being deleted
<B>Tcl_NRCreateCommand</B> does not create any command, does not delete any
command, and returns NULL.
<P>
<B>Tcl_NREvalObj</B> pushes a function that is like <B><A HREF="../TclLib/Eval.htm">Tcl_EvalObjEx</A></B> but
consumes no space on the C stack.
<P>
<B>Tcl_NREvalObjv</B> pushes a function that is like <B><A HREF="../TclLib/Eval.htm">Tcl_EvalObjv</A></B> but
consumes no space on the C stack.
<P>
<B>Tcl_NRCmdSwap</B> is like <B>Tcl_NREvalObjv</B>, but uses <I>cmd</I>, a token
previously returned by <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CreateObjCommand</A></B> or
<B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_GetCommandFromObj</A></B>, instead of resolving the first word of <I>objv</I>.
<P>
<B>Tcl_NRExprObj</B> pushes a function that evaluates <I>objPtr</I> as an
expression in the same manner as <B><A HREF="../TclLib/ExprLongObj.htm">Tcl_ExprObj</A></B> but without consuming space
on the C stack.
<P>
All of the functions return <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B> if the evaluation of the script,
command, or expression has been scheduled successfully.  Otherwise (for example
if the command name cannot be resolved), they return <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and store
a message as the interpreter's result.
<P>
<B>Tcl_NRAddCallback</B> pushes <I>postProcPtr</I>.  The signature for
<B>Tcl_NRPostProc</B> is:
<P>
<PRE>typedef int
<B>Tcl_NRPostProc</B>(
        <B>ClientData</B> <I>data</I>[],
        <B><A HREF="../TclLib/Interp.htm">Tcl_Interp</A></B> *<I>interp</I>,
        int <I>result</I>);</PRE>
<P>
<I>data</I> is a pointer to an array containing <I>data0</I> through <I>data3</I>.
<I>result</I> is the value returned by the previous function implementing part
the routine.
<H3><A NAME="M6">EXAMPLE</A></H3>
The following command uses <B><A HREF="../TclLib/Eval.htm">Tcl_EvalObjEx</A></B>, which consumes space on the C
stack, to evalute a script:
<P>
<PRE>int
<I>TheCmdOldObjProc</I>(
    ClientData clientData,
    <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *interp,
    int objc,
    <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *const objv[])
{
    int result;
    <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *objPtr;

    <I>... preparation ...</I>

    result = <B><A HREF="../TclLib/Eval.htm">Tcl_EvalObjEx</A></B>(interp, objPtr, 0);

    <I>... postprocessing ...</I>

    return result;
}
<B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CreateObjCommand</A></B>(interp, &quot;theCommand&quot;,
        <I>TheCmdOldObjProc</I>, clientData, TheCmdDeleteProc);</PRE>
<P>
To avoid consuming space on the C stack, <I>TheCmdOldObjProc</I> is renamed to
<I>TheCmdNRObjProc</I> and the postprocessing step is split into a separate
function, <I>TheCmdPostProc</I>, which is pushed onto the function stack.
<I><A HREF="../TclLib/Eval.htm">Tcl_EvalObjEx</A></I> is replaced with <I>Tcl_NREvalObj</I>, which uses a
trampoline instead of consuming space on the C stack.  A new version of
<I>TheCmdOldObjProc</I> is just a a wrapper that uses <B>Tcl_NRCallObjProc</B> to
call <I>TheCmdNRObjProc</I>:
<P>
<PRE>int
<I>TheCmdOldObjProc</I>(
    ClientData clientData,
    <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *interp,
    int objc,
    <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *const objv[])
{
    return <B>Tcl_NRCallObjProc</B>(interp, <I>TheCmdNRObjProc</I>,
            clientData, objc, objv);
}</PRE>
<P>
<PRE>int
<I>TheCmdNRObjProc</I>
    ClientData clientData,
    <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *interp,
    int objc,
    <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *const objv[])
{
    <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *objPtr;

    <I>... preparation ...</I>

    <B>Tcl_NRAddCallback</B>(interp, <I>TheCmdPostProc</I>,
            data0, data1, data2, data3);
    /* <I>data0 .. data3</I> are up to four one-word items to
     * pass to the postprocessing procedure */

    return <B>Tcl_NREvalObj</B>(interp, objPtr, 0);
}</PRE>
<P>
<PRE>int
<I>TheCmdNRPostProc</I>(
    ClientData data[],
    <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *interp,
    int result)
{
    /* <I>data[0] .. data[3]</I> are the four words of data
     * passed to <B>Tcl_NRAddCallback</B> */

    <I>... postprocessing ...</I>

    return result;
}</PRE>
<P>
Any function comprising a routine can push other functions, making it possible
implement looping and sequencing constructs using the function stack.
<P>
<H3><A NAME="M7">SEE ALSO</A></H3>
<B><A HREF="../TclLib/CrtCommand.htm">Tcl_CreateCommand</A></B>, <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_CreateObjCommand</A></B>, <B><A HREF="../TclLib/Eval.htm">Tcl_EvalObjEx</A></B>, <B><A HREF="../TclLib/CrtObjCmd.htm">Tcl_GetCommandFromObj</A></B>, <B><A HREF="../TclLib/ExprLongObj.htm">Tcl_ExprObj</A></B>
<H3><A NAME="M8">KEYWORDS</A></H3>
<A href="../Keywords/S.htm#stackless">stackless</A>, <A href="../Keywords/N.htm#nonrecursive">nonrecursive</A>, <A href="../Keywords/E.htm#execute">execute</A>, <A href="../Keywords/C.htm#command">command</A>, <A href="../Keywords/G.htm#global">global</A>, <A href="../Keywords/V.htm#value">value</A>, <A href="../Keywords/R.htm#result">result</A>, <A href="../Keywords/S.htm#script">script</A>
<H3><A NAME="M9">COPYRIGHT</A></H3>
Copyright &copy; 2008 Kevin B. Kenny.
Copyright &copy; 2018 Nathan Coulter.
<div class="copy"></div>
</BODY></HTML>
